BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / gt_power / gtread10.zip / GTREAD.DOC < prev next >

Wrap

Text File | 1990-07-10 | 34KB | 925 lines

GTRead The GT Offline Mail Reader Version 1.0 Released July 10, 1990 Copyright (C) 1990, Thoughtware and Stephen Russell Introduction Welcome to GTRead, an offline mail reader for users of GT bulletin-board systems. Using GTRead with GT's Fastmail system reduces the time you spend on the BBS, by letting you read and reply to mail at your leisure. This gives more time to other users of the BBS, gives you more time to upload or download files, and reduces your communication costs, particularly for long-distance calls. You can even automate the collection and sending of mail with the clever use of communication scripts. GTRead offers the following features: * Automatically extracts incoming mail from a Fastmail archive. * Supports multiple bulletin boards, with separate mail subdirectories for each board. * Window-based environment for browsing through message areas and viewing messages. * Edit replies with your favourite editor, with quoting of selected messages. Copyright and Distribution GTRead is copyrighted software, and may not be sold for profit. However, it may be freely distributed for strictly noncommercial use by individual GT BBS users. - 1 - GTRead Version 1.0 System Requirements GTRead is frugal in its use of memory, and fits in 128K. It must however coexist in memory with other programs such as an editor and archiver. As a result, the minimum memory requirement is probably 512K. GTRead does not keep copies of messages in memory, but reads them from disk as needed. While it is possible to use GTRead with a floppy-only system, it will be slow. Best performance is obtained with a hard disk system, particularly with a cache. A hard disk system is also recommended if you plan to process mail from several systems. GTRead will work with all display adapters, and with DESQview. It can be configured for old CGA adapters that suffer from screen snow, and to always use the BIOS for screen accesses. Using BIOS mode is not encouraged, though, as it is particularly slow. -------------------- Installing GTRead There are a few steps involved in installing GTRead. Start by extracting all of the files in the distribution archive into an empty subdirectory. You should then read the section below on mail subdirectories, and decide how you will configure your mail system. Next, run GTRConf to configure GTRead for your system. The last step is to move the files GTREAD.EXE, GTREAD.HLP and HOSTLIST.TXT to their appropriate subdirectories. GTREAD.EXE would normally be moved to one of the subdirectories on your PATH. Alternatively, you might move it to your GT mail directory, or some other directory. In this case, you must first CD to that directory before running GTRead. Details of installing the other files are given below. Once you've installed GTRead, you may delete the GTRCONF.EXE program if you are short of disk space. Make sure you have a backup copy, though, in case you wish to reconfigure GTRead in the future. Mail Subdirectories Before you can run GTRConf, you need to choose one of three different ways to configure your mail system. The simplest approach is to do nothing. If you use GTRead without specifying a mail subdirectory, GTRead will look in the current subdirectory for Fastmail archives and GT mail files. Any mail you write will be saved in the current directory, as is your reply archive ready for uploading. - 2 - GTRead Version 1.0 The next alternative is to set up a single subdirectory for your GT mail; for example, "C:\GTMAIL". You then use GTRConf to inform GTRead of the name for this subdirectory. GTRead will switch to this directory before looking for the mail archive and files. When you exit GTRead, you'll be returned to your original directory. This approach is best if you receive mail from only one GT system. If you intend to receive mail from several GT systems, however, you should create separate subdirectories for each system. These subdirectories are created in two steps. First, create a top-level subdirectory, such as C:\GTMAIL, and CD to that directory. Then create a subdirectory for each GT system you receive mail from. One possibility for naming these subdirectories is to use the system's net and node numbers. The following example shows how to create mail directories for the systems 302/003, 302/006 and 302/109. Note that a hyphen is used instead of a slash to make a legal MSDOS directory name. mkdir c:\gtmail cd c:\gtmail mkdir 302-003 mkdir 302-006 mkdir 302-109 Alternatively, you might choose more descriptive names based on the GT boards' names. Whichever approach you choose, keep a list of the directory names handy to edit the HOSTLIST.TXT file described later. You can add more subdirectories later without running GTRConf; just add new entries to HOSTLIST.TXT. Using GTRConf The GTRConf program is used to install and configure GTRead. GTRConf's main menu allows you to customise the screen colours, pick the programs that pack and unpack mail archives, select the style of quoting for messages included in your replies, and tell GTRead where your mail files will be kept. The following sections describe each of these configuration options. The Directories menu The Directories option of GTRConf's main menu allows you to enter the name of your mail directory. This should be the full pathname of the directory, such as "C:\GTMAIL" (don't forget the drive prefix and the backslash). If you don't want to use a mail directory, leave the entry blank. If you have decided to have multiple mail subdirectories, you may also specify the name of the subdirectory for your `preferred' GT system; for example, 302-003. GTRead will then check for mail from this board first. You can change to other boards using GTRead's Board command. - 3 - GTRead Version 1.0 Setting the screen colours There are four choices for setting GTRead's use of colours. If you select the Default option, GTRead will check the kind of display adapter in your computer and use either monochrome or a preselected set of colours as appropriate. This decision can be overridden using either the Colour or Monochrome options. The latter is useful if you are using a monochrome screen with a colour adapter such as a CGA. The Custom option allows you to change the screen colours to whatever you like. You can select the colours for the text, borders, titles and selection bars of the background, the menu bar, the browser, message and help windows, and the dialogue boxes. As you make the changes, GTRConf will show an example GTRead screen. Use the arrow keys to move around the palette box and select the colour you want. Setting Video Modes This option allows you to force GTRead to use the BIOS for all screen access, and to stop `snow' on old CGA adapters. BIOS mode is very slow, however, so only use it if absolutely necessary. The Programs menu GTRConf's Programs command is used to specify the names of your archive pack and unpack programs, and the editor to be used for editing mail. You don't need to give the full path for each program; GTRead will search the subdirectories specified by your PATH environment variable, and will add an EXE or COM suffix as needed. There is a slight speed advantage in specifying the full path and extension, though, so that GTRead doesn't have to search. This will be most apparent for floppy disk systems. Choosing an editor GTRead doesn't come with an editor, though you need one to create mail. The editor you choose should meet a few basic requirements. First, it should be small, as it is reloaded from disk every time you edit a message, and it must coexist in memory with GTRead. If you are using a RAM disk, you can speed up loading the editor by keeping a copy in the RAM disk. Make sure that the RAM disk is included in your PATH, or give the full path including the drive designator (for example, "F:\MYED.EXE"). Second, the editor must accept and produce plain ASCII (non-document) files. Sending a wordprocessor's document format as mail will probably produce garbage when displayed at the other end. Last, your editor must accept the name of the file to be edited from the command line. Some editors insist on always showing a menu of the files available for editing. Unfortunately, GTRead's mail files are named using cryptic codes, so picking the right - 4 - GTRead Version 1.0 file from the menu will be difficult. There are many shareware editors available if you don't have a suitable editor. Check what your local bulletin board has to offer. The pack and unpack programs To reduce download times, GT's Fastmail files are sent as compressed archives. Similarly, GTRead compresses your mail for uploading. You must tell Fastmail which compression programs to use, and have a matching set of programs on your computer. Example programs include ARC, PAK, LHARC, and PKZIP/PKUNZIP. The actual compression programs offered by Fastmail may vary among GT systems. You should choose a common `standard' for all of the systems you intend to use with GTRead. Some archiving programs, such as ARC, PAK and LHARC, combine compression and decompression into a single program. To support these programs, GTRConf allows you to specify the command line options that select the appropriate action. For example, if you are using the ARC program, set the Archive Options to "a" (add files to archive), and the Unarchive Options to "x" (extract from archive). Quoting When replying to a message, you will often wish to quote part of the message or some earlier messages. Each line of the quotation is preceded by a prefix, usually "> ". This can be changed using the Quoting option. You can also configure GTRead to never automatically quote the message, always quote it, or to ask first. If you choose the first option, you can still use GTRead's Quote command to selectively quote messages before replying. Please keep your quotes as short as possible! There is usually little point in quoting all of the original message. Just retain enough of the original to keep its meaning and to show what you are responding to. -------------------- Installing The GTRead Files Having configured GTRead, the last step is to install the support files where GTRead can find them. The next sections describe the purpose of these files and how to install them. The HOSTLIST.TXT file This file is used by GTRead to identify the source of incoming mail. As well, if you decide to have multiple mail subdirectories, HOSTLIST.TXT contains the names of each of these subdirectories and which systems they correspond to. - 5 - GTRead Version 1.0 HOSTLIST.TXT contains one line for each GT system from which you receive mail. Each line consists of three fields separated by colons, as shown below. 302/000:<nodir>:The Poet's Dilemma 302/003:302-003:The Black Hole The first field gives the net and node number of the GT system. The second field is the name of that system's mail subdirectory, and the last field is the name of the system. As the first line shows, the second field should be set to "<nodir>" if that system has no mail subdirectory. Before installing HOSTLIST.TXT, you may need to edit it to match your configuration. If you've set up separate mail subdirectories for each GT system, edit the directory fields to the names you chose for each subdirectory. This allows GTRead's Board command to find the directory containing the mail from each system. Once you've edited HOSTLIST.TXT, it should be installed in a directory where GTRead can find it. GTRead looks for the file in your main mail directory; if you don't have a mail directory, GTRead will look in the current directory. So, if you have configured GTRead to use a mail directory, you should copy HOSTLIST.TXT to that directory. If GTRead can't find the file, the GTRead Board command is disabled, and mail displays will just show the source's net/node number. Installing GTREAD.HLP GTRead's online help facility uses the GTREAD.HLP file, which should be installed so that GTRead can find it. GTRead first searches the directories specified in your PATH variable. If it doesn't find the file, it also looks in your main mail directory (or the current directory if no mail directory has been specified). You should copy GTREAD.HLP to one of these directories. -------------------- Downloading Mail If you've not used GT's Fastmail system before, the following paragraphs provide a brief description. You can obtain further information from your local GT system. Access to the Fastmail system is obtained using GT's Open door command. Fastmail scans the message areas to find messages you haven't read, then presents a menu of commands to select the message areas of interest, change the number of messages to be sent, etc. Once you've chosen the messages you want, you have the choice of downloading only mail addressed to you, or all mail from your selected areas. Fastmail then compresses your mail into a file called FASTMAIL.ZIP (the extension may be different, - 6 - GTRead Version 1.0 depending on your choice of archiver), and sends the file to you using your selected download protocol. The GT UNjoin command allows you to specify message areas which don't interest you. Fastmail will then ignore these areas. This command is very useful, given the large total volume of mail each day. Before using Fastmail for the first time, use UNjoin to reduce the number of active areas. Some notes on downloading There are a few points you should keep in mind about downloading mail. * Be careful that you don't overwrite an existing Fastmail file. Fortunately, most file transfer programs will avoid this by changing the file's extension. GTRead supports this by unpacking all Fastmail files it finds. * Zmodem's crash recovery option should be disabled, though, or Zmodem may `continue' the download by appending to the old Fastmail file, destroying both archives. * If you receive mail from multiple GT systems, you should ensure that each Fastmail file is downloaded to the appropriate mail subdirectory. If you don't do this, GTRead will not be able to find it. -------------------- - 7 - GTRead Version 1.0 Using GTRead GTRead is easy to use, due to its extensive use of menus and windows. The F1 key allows you to get help at any time. The following notes describe GTRead's operation, and provide a brief description of GTRead's various commands. GTRead would normally be used after you have downloaded a Fastmail archive. GTRead's Unpack command will extract the mail file from the archive, then display a summary of the message areas. You can then view the messages in each area. The Thread command allows you to follow the messages on a particular subject, and you can Kill topics that don't interest you. If you are feeling antisocial, you can also Ignore particular authors. After you've scanned a particular thread, the Next command jumps back to the first message that you haven't read. The Quote command allows you to collect quotes from several messages, which are used when you Reply to a message, or Add a new message. Interesting messages can be Saved. After you've finished processing your mail, the Pack command constructs a FASTRPLY archive ready for uploading. Menus The top line of the screen is used by GTRead to display a menu of the available commands. These will change depending on the context. Each command is selected by typing the highlighted letter. In the descriptions below, the command letter is enclosed in parentheses; for example, "(B)oard". Sometimes a command will be disabled, in which case no letter in that menu item will be highlighted. Selection windows GTRead uses windows to display lists of items from which you can make a selection. Move around the list using the arrow keys, then press Enter to make the selection. Pressing Esc will close the window without making a selection. Startup Start GTRead running by typing "GTREAD" at the DOS prompt. If you are using a monochrome display with a colour adapter, you should type "GTREAD M" if you haven't selected monochrome mode with GTRConf. GTRead starts by changing to your selected mail directory (if any) and loads the HOSTLIST.TXT file. If you have selected a preferred board to start in, GTRead then switches to that board's directory. GTRead then checks for the presence of any Fastmail archives or GT mail files before displaying the main menu. GTRead's main menu provides the following commands: (B)oard The Board command allows you pick a GT system from the list in the HOSTLIST.TXT file, and changes to the mail - 8 - GTRead Version 1.0 subdirectory of that system. GTRead then checks for the presence of any Fastmail archives or GT mail files. This command is only enabled if GTRead found the HOSTLIST.TXT file at startup. (U)npack mail The Unpack command extracts the mail files from any Fastmail archives in the current directory. Each archive is then deleted. Fastmail assigns a name of the form "MAILmmdd.TXT" to each mail file, where "mmdd" indicates the month and day that the mail was sent. GTRead renames the file to "yyyymmdd.GTM", where "yyyy" is the year, and "GTM" is used to indicate a GT mail file. This renaming is done for users who like to archive old mail files for future reference, and to make the mail files easier for GTRead to find. If you download more than one mail archive in the same day, GTRead uses the extensions "GT1", "GT2", etc. Unfortunately, these are not necessarily in the same order as the file's were received. If the Unpack command is successful, the Open command is automatically invoked to display the contents of the last archive processed. (O)pen mail The Open command displays a list of all the GTM files in the current directory. The selected mail file is then scanned by GTRead to extract information about each message. As well, GTRead searches for any replies or added messages from an earlier GTRead session. This allows you to process your mail in several GTRead sessions. If the mail file is successfully scanned, GTRead displays a list of all the message areas in the mail file. Use the arrow keys to highlight one of the message areas, then press Enter to see the messages for that area. If the mail directory contains a FASTRPLY reply archive, the Open command offers you the option of extracting the mail in the archive that belongs to the current mail file. These messages can then be viewed and edited before being repacked. Note that if there is no mail in the archive for the current mail file, GTRead may report that the unpacking failed. This error message can be ignored. NOTE: Due to a limitation in GTRead, it is advisable to extract mail from the FASTRPLY archive if the archive contains new messages (generated with the Add command) and you intend to add further new messages. Failure to do so will cause the new messages to be assigned the same message numbers as the earlier ones. The earlier messages will then be overwritten when the archive is repacked. This problem will be fixed in a later release. - 9 - GTRead Version 1.0 (P)ack replies Once you have finished creating replies and new messages, the Pack command constructs a FASTRPLY reply archive for uploading. If the FASTRPLY archive already exists, the new mail is added to the archive. If the archive is successfully created or updated, the reply and new message files are deleted. All mail in the current mail directory is packed, not just that for the current mail file. This allows you to combine several lots of mail in one step. Although the Open command allows you to extract mail from the reply archive, there is a problem in then killing that mail. GTRead's Kill and Unreply commands only delete the individual message files, and don't delete the copy in the archive. So if you have second thoughts about a message after you've packed the replies, you have to exit to DOS and delete the files in the archive manually. This is not easy, though, as the file names used by GTRead are cryptic. One approach to finding the right name is to use GTRead to pick the message or reply, then invoke your editor using the Edit command and ask the editor what the file name is! The moral is simple: don't pack replies until you're truly finished. (D)OS The DOS command jumps to DOS in the current mail directory. This is useful if you need to do some housekeeping, such as deleting old mail files. e(X)it Exit GTRead and return to DOS. The Messages Window and Menu Once you've opened a mail file and selected a message area, GTRead will present a summary of the messages in that area. The summary shows who wrote the message, who it was addressed to, and the subject of the message. Pressing Enter will show the contents of the highlighted message. The following special symbols are used to indicate the status of each message. The message is addressed to you. ■ The message has been Viewed, Killed or Ignored. The message is marked for Quoting or Saving. You have entered a reply for this message. - 10 - GTRead Version 1.0 New message entered by you. The message menu offers the following commands: (V)iew Display the highlighted message, even if it has been Killed or Ignored. The Enter key performs the same function. (N)ext Display the first message not yet Viewed. This command would normally be used after following all messages in a particular thread, as it jumps back to the first unread topic. (T)hread Display the next message with the same subject as the current message. (M)ark Toggle the mark for the current message. Can also be done by pressing the space bar. See the Quote and Save command for descriptions of how marked messages are used. (Q)uote Each of the marked messages, or just the current message if none are marked, is added to the Quote buffer. The quoted messages are then included in the next message you create with the Reply or Add commands. The contents of the Quote buffer are preserved even if you change message areas, or use the main menu's Open or Board commands. This allows you to quote messages from old mail files, or mail received from other boards. (R)eply Generate a reply to the current message, or edit an existing reply. For new replies, GTRead prompts for the subject of the message, and whether the message is private or should be protected. Any quoted messages are added to the reply. The current message may also be quoted, depending on the quoting mode you chose with GTRConf. GTRead will then invoke your editor to edit the reply file. The quote buffer is cleared after a Reply command. However, you can use the Quote command again to collect more quotes, and Reply to the message a second time. The quoted material is appended to the existing reply, ready for further editing. (A)dd Allows you to enter a new message for uploading to the current area. Any quoted messages are included for editing, and the quote buffer is then cleared. - 11 - GTRead Version 1.0 (E)dit If the current message has a reply, edit the reply file. This is different from using the Reply command again, as it does not append any quotes first. Alternatively, if the current message has been Added, edit the new message. (S)ave The marked messages, or the current message, are appended to a file. By default, the messages will be saved in the file "MAILBOX.TXT", but this can be changed by entering a new name when prompted. One non-obvious use of the Save command is to `save' the messages to a DOS device. For example, saving to PRN will actually print the messages. (K)ill If the current message is from a downloaded mail file, all other messages with the same subject are marked as read and will be ignored by the Next and Thread commands. However, if the message is a new message Added by you for uploading, the message is deleted. (Also see the Pack command above for further comments about deleting messages.) (I)gnore Similar to the Kill command, except that it ignores all messages from the author of the current message. e(X)it Return to the main menu. Pressing Esc has the same effect. -------------------- The View Window and Menu Selected messages are displayed in a full-screen window, along with the the menu bar and a status line. Use the arrow keys, PgUp, PgDn, Home and End to move around within the message. The commands offered by the View Menu are mostly similar to the Message Menu, with the following differences: (N)ext If all messages in the current area have been read, Next is equivalent to the "+" key described below. (Q)uote (S)ave Only quotes or saves the current message, ignoring any marked messages. (M)ark Always sets the mark for the current message. (U)nreply Allows you to delete the reply to the current message, if any. See the Pack command above for details on deleting - 12 - GTRead Version 1.0 replies after they have been added to the reply archive. (K)ill (I)gnore Kills or ignores the current message, then performs a Next command. +/- The "+" and "-" keys allow you to move to the next or previous message, regardless of whether the message has been Killed or Ignored, or has already been read. e(X)it Return to the Message Menu. -------------------- Uploading Your Replies GTRead's Pack command constructs a file called FASTRPLY.ZIP in the current mail directory. This archive contains the individual messages, plus a special header file used by Fastmail. To upload the FASTRPLY archive, call the GT board, use the Open command to start Fastmail running, then pick the "Upload your replies" command. Fastmail prompts when it is ready to receive your mail file. Use your communication program's upload command to send your FASTRPLY.ZIP file. If the file is received successfully, Fastmail displays a brief summary of each message you've sent. If you're processing mail from several GT boards, make sure you send each FASTRPLY.ZIP file to the correct board. If you upload mail to the wrong board, Fastmail will reject it. No harm is done, but you have wasted a few minutes of your time. Remember to delete the FASTRPLY.ZIP file after you've uploaded it. If you forget, any new mail you create later will be added to the old archive, and when you upload it, your old messages will be posted again. BUGS This version of GTRead has several known limitations. The amount of memory available for keeping track of the status of individual messages is limited. Each message requires around 70 bytes of storage, although this will vary depending on the number of unique subjects and names in the message headers. As there is around 40Kbytes available, GTRead can cope with around 400-500 messages per mail file. If GTRead runs out of memory, it switches to `panic' mode and throws away the information about every message. When a message area is then selected, the information about the messages in that area is reloaded by rescanning the mail file, searching for - 13 - GTRead Version 1.0 replies, etc. This is tedious, but allows GTRead to cope with about 400-500 messages per area, at a pinch. However, the information about whether each message has been viewed, killed or ignored is lost when a new area is selected. This code has not been well tested, either. It is therefore advisable to limit the size of mail files, by being selective in your choice of message areas and by downloading mail regularly. If you exit GTRead, it will forget which messages have been read, killed or ignored. It would be nice to save the status of each message, but this is made difficult by the memory panic mode. Message numbers are assigned to new messages by searching for existing messages when a mail file is opened. The new message numbers then follow in sequence. This approach can fail, however, if you Add new messages, Pack your mail, Open the mail file again _w_i_t_h_o_u_t extracting mail from the reply archive, then Add more mail. The workaround for now is to always extract mail from the archive. This will be fixed in a later release of GTRead. - 14 -